home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / cpp_libs / cool / ge_cool.lha / GE_COOL2.1 / man / oldman3 / Association.3T next >
Text File  |  1992-06-29  |  10KB  |  335 lines
  1. .TH ASSOCIATION
  2. .SH NAME
  3. Association<Ktype,Vtype>\f1  A dynamic, parameterized association
  4. .SH SYNOPSIS
  5. #include <cool/Association.h>
  6. .SH DESCRIPTION
  7. The \f3Association<Ktype,Vtype>\f1 class is privately derived from the 
  8. \f3Vector<Type>\f1 class and implements a collection of pairs. The first of the pair 
  9. is called the 
  10.  key , 
  11. and the second of the pair is called the 
  12.  value . 
  13. The  
  14. \f3Association<Ktype,Vtype>\f1 class implements a one-dimensional vector 
  15. parameterized over a pair of objects. The first type specifies the type of the 
  16. key, and the second type specifies the type of the value. Many of the member 
  17. functions for \f3Association<Ktype,Vtype>\f1 are inherited from \f3Vector<Type>\f1 and, 
  18. consequently, are inline calls to the vector member function of the same name.
  19. .PP
  20. The \f3Association<Ktype,Vtype>\f1 class inherits the dynamic growth capability of 
  21. the 
  22.  Vector 
  23. class. Vectors are, by default, dynamic in nature. A static-sized 
  24. vector object is selected by setting the growth allocation size to zero or by 
  25. passing in a pointer to a block of user-supplied storage to the constructor. If 
  26. a vector is of static size and an operation is performed that requires more 
  27. storage, an 
  28.  \f3\f3Error\f1\f1 
  29. exception is raised.
  30. .PP
  31. The \f3Association<Ktype, Vtype> \f1class implements the notion of a current 
  32. position. This is useful for iterating through the elements of a vector. The 
  33. current position is maintained in a data member of type 
  34.  Association_state 
  35. and is set or reset by all member functions affecting elements in the class. Member 
  36. functions are provided to reset the current position, move to the next and 
  37. previous elements, find an element, and get the value at the current position. 
  38. The \f3Iterator<Type>\f1
  39. class provides a mechanism to save and restore the state 
  40. associated with the current position, thus allowing the programmer to use 
  41. multiple iterators over the same instance of an association object.
  42. .SH Base Classes
  43. \f3Vector<Type>, Vector, 
  44. .SH Friend Classes
  45. None
  46. .SH Constructors
  47. .TP
  48. \f3Association<Ktype,Vtype> ();\f1
  49. Creates an empty association of the specified type.
  50. .TP
  51. \f3Association<Ktype,Vtype> (const Association<Ktype,Vtype>& \f3assoc);\f1
  52. Duplicates the size and value of an association object.
  53. .TP
  54. \f3Association<Ktype,Vtype> \f3(unsigned long \f2number);\f1
  55. Allocates enough storage for an association of a specific type to hold 
  56.  number 
  57. elements.
  58. .TP
  59. \f3Association<Type> (void* \f2storage\f3, unsigned long \f2number\f3);\f1
  60. Creates a static-sized association object for
  61.  number 
  62. elements whose storage 
  63.  storage 
  64. is provided by the user. If an object of this type attempts to grow 
  65. dynamically or the programmer invokes the 
  66.  resize 
  67. member function, an 
  68.  \f3\f3Error\f1\f1 
  69. exception is raised.
  70. .SH Member Functions
  71. .TP
  72.  inline long capacity ();
  73. Returns the maximum number of elements the association can contain.
  74. .TP
  75.  inline void clear ()
  76. Removes all elements in the object and invalidates the current position.
  77.  
  78. .TP
  79.  inline Association_state& current_position ();
  80. Returns the state information associated with the current position. This 
  81. function should be used with the \f3Iterator<Type>\f1 class to save and restore the 
  82. current position, thus facilitating multiple iterators over an instance of 
  83. association.
  84. .TP
  85. \f3Boolean find (const Ktype& key\f3);\f1
  86. Searches the association for
  87.  key . 
  88. If found, this function sets the current 
  89. position and returns 
  90.  
  91.  TRUE ; 
  92. otherwise, this function resets the current position 
  93. and returns
  94.  
  95.  FALSE .
  96. .TP
  97. \f3Boolean get (const Ktype& key, Vtype& value\f3);\f1
  98. Gets the associated 
  99.  value 
  100. for 
  101.  key . 
  102. This function returns 
  103.  
  104.  TRUE 
  105. and modifies 
  106.  value 
  107. to contain the associated value. If
  108.  key 
  109. is not found, this function 
  110. returns 
  111.  
  112.  FALSE 
  113. and does not modify 
  114.  value .
  115. .TP
  116. \f3Boolean get_key (const Vtype& value, Ktype& key\f3) const;\f1
  117. Gets the first associated 
  118.  key 
  119. for 
  120.  value . 
  121. This function returns 
  122.  
  123.  TRUE 
  124. and modifies 
  125.  key 
  126. to contain the associated key. If 
  127.  value 
  128. is not found, this 
  129. function returns 
  130.  
  131.  FALSE 
  132. and does not modify
  133.  key .
  134. .TP
  135. \f3inline const Ktype& \f3key () const;\f1
  136. Returns the key of the key/value pair at the current position.
  137. .TP
  138.  inline long length ();
  139. Returns the number of elements (pairs) in the association.
  140. .TP
  141.  inline Boolean next ();
  142. Advances the current position pointer to the next element in the association 
  143. and returns 
  144.  
  145.  TRUE . 
  146. If the current position is invalid, this function advances to 
  147. the first element and returns 
  148.  
  149.  TRUE . 
  150. If advancing past the last element, this 
  151. function invalidates the current position and returns
  152.  
  153.  FALSE .
  154. .TP
  155. \f3Association<Ktype,Vtype>& \f3operator= (const Association<Ktype,Vtype>>>&\f3);\f1
  156. Overloads the assignment operator for the 
  157.  Association 
  158. class and assigns one 
  159. association object to have the value of another by duplicating the size and 
  160. element values. This function invalidates the current position. If the 
  161. association is prohibited from dynamically growing as necessary, an 
  162.  \f3\f3Error\f1\f1 
  163. exception is raised.
  164. .TP
  165. \f3Boolean operator== (const Association<Ktype,Vtype>& assoc\f3) const;\f1
  166. Overloads the equality operator for the 
  167.  Association 
  168. class. This function 
  169. returns 
  170.  
  171.  TRUE 
  172. if the associations have the same number of elements with the same 
  173. values; otherwise, this function returns
  174.  
  175.  FALSE .
  176. .TP
  177. \f3inline Boolean operator!= (const Association<Ktype,Vtype>& assoc\f3) const;\f1
  178. Overloads the inequality operator for the 
  179.  Association 
  180. class. This function 
  181. returns 
  182.  
  183.  TRUE 
  184. if the associations have a different number of elements or 
  185. different values; otherwise, this function returns 
  186.  
  187.  FALSE .
  188. .TP
  189.  inline Boolean prev ();
  190. Moves the current position pointer to the previous element in the association 
  191. and returns 
  192.  
  193.  TRUE . 
  194. If the current position is invalid, this function moves to 
  195. the last element and returns 
  196.  
  197.  TRUE . 
  198. If moving to the previous element passes the 
  199. first element in the association, this function invalidates the current 
  200. position and returns
  201.  
  202.  FALSE .
  203. .TP
  204. \f3Boolean put (const Ktype& key\f3, const Vtype& value\f3);\f1
  205. Puts the 
  206.  key/value 
  207. pair into the association. If a pair already exists with the 
  208. specified key, the value for that pair is replaced with 
  209.  value . 
  210. If required and 
  211. not prohibited, the association is grown. If the new pair is successfully put 
  212. into the association, 
  213.  
  214.  TRUE 
  215. is returned; otherwise,
  216.  
  217.  FALSE 
  218. is returned.
  219. .TP
  220.  Vtype& remove ();
  221. Removes and returns a reference to the element at the current position. This 
  222. function sets the current position to the element immediately following the 
  223. element removed.  If the element removed is at the end of the association, this 
  224. function invalidates the current position. If the current position is invalid, 
  225. and 
  226.  \f3\f3Error\f1\f1 
  227. exception is raised.
  228. .TP
  229. \f3Boolean remove (const Ktype& key\f3);\f1
  230. Searches for
  231.  key 
  232. and, if found, this function removes the pair associated with 
  233.  key 
  234. and sets the current position to the element immediately following the 
  235. element removed; then, the function returns 
  236.  
  237.  TRUE . 
  238. If 
  239.  key 
  240. is found at the end of 
  241. the association, this function invalidates the current position and returns 
  242.  
  243.  TRUE . 
  244. If 
  245.  key 
  246. is not found, this function returns 
  247.  
  248.  FALSE .
  249. .TP
  250.  inline void reset ();
  251. Invalidates the current position.
  252. .TP
  253. \f3inline void resize (long \f2number\f3);\f1
  254. Resizes the association for at least 
  255.  number 
  256. elements. If a growth ratio has 
  257. been selected and it satisfies the resize request, the association is grown by 
  258. this ratio. This function invalidates the current position. If the size 
  259. specified is zero or negative, an 
  260.  \f3\f3Error\f1\f1 
  261. exception is raised.
  262. .TP
  263. \f3inline void set_alloc_size (int \f2size\f3);\f1
  264. Updates the allocation growth size to be used when the growth ratio is zero. 
  265. Default allocation growth size is 100 bytes.  If the size specified is 
  266. negative, an 
  267.  \f3\f3Error\f1\f1 
  268. exception is raised.
  269. .TP
  270. \f3inline void set_growth_ratio (float \f2ratio\f3);\f1
  271. Updates the growth ratio for this instance of an association to the specified 
  272. value. When an association needs to grow, the current size is multiplied by the 
  273. ratio to determine the new size. If 
  274.  ratio 
  275. is negative, an 
  276.  \f3\f3Error\f1\f1 
  277. exception is raised.
  278. .TP
  279. \f3void set_key_compare (\f2Assoc_Key_Compare \f3= NULL);\f1
  280. Updates the key compare function for this class of association. 
  281.  Assoc_Key_Compare 
  282. is a function of type
  283.  Boolean 
  284. (\f2*Function\f1)(\f3const Type&\f1, \f3const Type&\f1). If no argument is provided, the 
  285.  operator==
  286. for 
  287.  Ktype
  288. over which the key for the association class is parameterized is used.
  289. .TP
  290. \f3inline long set_length (long \f2number\f3);\f1
  291. Specifies the 
  292.  number 
  293. of elements in an association to allow random access via 
  294. the overloaded 
  295.  operator[\^] 
  296. member function. If 
  297.  number 
  298. is larger than the storage allocated, this function truncates 
  299.  number 
  300. to the largest value the allocated size will support. This function returns the updated number of elements.
  301. .TP
  302. \f3void set_value_compare (\f2Assoc_Value_Compare \f3= NULL);\f1
  303. Updates the value compare function for this class of association. 
  304.  Assoc_Value_Compare 
  305. is a function of type 
  306.  Boolean 
  307. (\f2*Function\f1)(\f3const Ktype&\f1, \f3const Vtype&\f1). If no argument is provided, the 
  308.  operator== 
  309. for 
  310.  Vtype 
  311. over which the value for the association class is parameterized is used.
  312. .TP
  313.  inline Vtype& value ();
  314. Returns a reference to the value of the key/value pair at the current position.
  315. .SH Friend Functions
  316. .TP
  317. \f3friend ostream& operator<< (ostream& \f2os,\f3 const  Association<Ktype,Vtype>& assoc\f3);\f1
  318. Provides a formatted output capability for reference to an 
  319. \f3Association<Ktype,Vtype>\f1 object.
  320. .TP
  321. \f3inline friend ostream& operator<< (ostream& \f2os\f3, const  Association<Ktype,Vtype>* assoc\f3);\f1
  322. Provides a formatted output capability for a pointer to an 
  323. \f3Association<Ktype,Vtype>\f1 object.
  324. .SH COPYRIGHT
  325.  
  326. Copyright (C) 1991 Texas Instruments Incorporated.
  327.  
  328. Permission is granted to any individual or institution to use, copy, modify,
  329. and distribute this software, provided that this complete copyright and
  330. permission notice is maintained, intact, in all copies and supporting
  331. documentation.
  332.  
  333. Texas Instruments Incorporated provides this software "as is" without
  334. express or implied warranty.
  335.